home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / KeyPairGenerator.java < prev    next >
Text File  |  1998-09-22  |  7KB  |  189 lines
  1. /*
  2.  * @(#)KeyPairGenerator.java    1.11 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.security;
  16.  
  17. /**
  18.  * The KeyPairGenerator class is used to generate pairs of
  19.  * public and private keys. Key generators are constructed using the
  20.  * <code>getInstance</code> factory methods (static methods that
  21.  * return instances of a given class).
  22.  * 
  23.  * <p>Key generation is an area that sometimes
  24.  * does not lend itself well to algorithm independence. For example,
  25.  * it is possible to generate a DSA key pair specifying key family
  26.  * parameters (p, q and g), while it is not possible to do so for
  27.  * an RSA key pair. That is, those parameters are applicable to DSA
  28.  * but not to RSA.
  29.  * 
  30.  * <P>There are therefore two ways to generate a key pair: in an 
  31.  * algorithm-independent
  32.  * manner, and in an algorithm-specific manner. The only difference
  33.  * between the two is the initialization of the object. 
  34.  * 
  35.  * <p>All key pair generators share the concepts of a "strength" and a
  36.  * source of randomness. The measure of strength is universally shared 
  37.  * by all algorithms,
  38.  * though it is interpreted differently for different algorithms.
  39.  * The <a href = "#initialize ">initialize</a> method in this 
  40.  * KeyPairGenerator class 
  41.  * takes these two universally shared
  42.  * types of arguments. 
  43.  * 
  44.  * <p>Since no other parameters are specified when you call this
  45.  * algorithm-independent <code>initialize</code>
  46.  * method, all other values, such as algorithm parameters, public
  47.  * exponent, etc., are defaulted to standard values. 
  48.  * 
  49.  * <P>
  50.  * It is sometimes desirable to initialize a key pair generator object
  51.  * using algorithm-specific semantics. For example, you may want to
  52.  * initialize a DSA key generator for a given set of parameters 
  53.  * <code>p</code>, <code>q</code> and <code>g</code>,
  54.  * or an RSA key generator for a given public exponent.
  55.  * 
  56.  * <P>
  57.  * This is done through algorithm-specific standard interfaces. Rather than
  58.  * calling the algorithm-independent KeyPairGenerator <code>initialize</code>
  59.  * method, the key pair generator is cast to an algorithm-specific interface 
  60.  * so that one of its specialized parameter initialization methods can be
  61.  * called. An example is the DSAKeyPairGenerator interface (from
  62.  * <code>java.security.interfaces</code>).
  63.  * 
  64.  *  <p>See <a href =
  65.  * "../guide/security/CryptoSpec.html#KPG">The KeyPairGenerator Class</a> 
  66.  * in the "Java Cryptography Architecture API Specification & Reference"
  67.  * for more information and examples.
  68.  * 
  69.  * @see java.security.interfaces.DSAKeyPairGenerator
  70.  */
  71. public abstract class KeyPairGenerator {
  72.  
  73.     private String algorithm;
  74.  
  75.     /**
  76.      * Creates a KeyPairGenerator object for the specified algorithm.
  77.      *
  78.      * @param algorithm the standard string name of the algorithm. 
  79.      * See Appendix A in the <a href=
  80.      * "../guide/security/CryptoSpec.html#AppA">
  81.      * Java Cryptography Architecture API Specification & Reference </a> 
  82.      * for information about standard algorithm names.
  83.      */
  84.     protected KeyPairGenerator(String algorithm) {
  85.     this.algorithm = algorithm;
  86.     }
  87.     
  88.     /**
  89.      * Returns the standard name of the algorithm for this key generator.
  90.      * See Appendix A in the <a href=
  91.      * "../guide/security/CryptoSpec.html#AppA">
  92.      * Java Cryptography Architecture API Specification & Reference </a> 
  93.      * for information about standard algorithm names.
  94.      * 
  95.      * @return the standard string name of the algorithm. 
  96.    */
  97.     public String getAlgorithm() {
  98.     return algorithm;
  99.     }
  100.  
  101.     /**
  102.      * Generates a KeyPairGenerator object that implements the algorithm
  103.      * requested, as available in the environment.
  104.      *
  105.      * @param algorithm the standard string name of the algorithm. 
  106.      * See Appendix A in the <a href=
  107.      * "../guide/security/CryptoSpec.html#AppA">
  108.      * Java Cryptography Architecture API Specification & Reference </a> 
  109.      * for information about standard algorithm names.
  110.      *
  111.      * @return the new KeyPairGenerator object.
  112.      *
  113.      * @exception NoSuchAlgorithmException if the algorithm is
  114.      * not available in the environment.  
  115.      */
  116.     public static KeyPairGenerator getInstance(String algorithm)
  117.     throws NoSuchAlgorithmException {
  118.     try {
  119.         return (KeyPairGenerator)Security.getImpl(algorithm, 
  120.                               "KeyPairGenerator",
  121.                               null);
  122.     } catch(NoSuchProviderException e) {
  123.         throw new InternalError("please send a bug report via " + 
  124.                     System.getProperty("java.vendor.url.bug"));
  125.     }
  126.     }
  127.  
  128.     /** 
  129.      * Generates a KeyPairGenerator object implementing the specified
  130.      * algorithm, as supplied from the specified provider, 
  131.      * if such an algorithm is available from the provider.
  132.      *
  133.      * @param algorithm the standard string name of the algorithm.
  134.      * See Appendix A in the <a href=
  135.      * "../guide/security/CryptoSpec.html#AppA">
  136.      * Java Cryptography Architecture API Specification & Reference </a> 
  137.      * for information about standard algorithm names.
  138.      *
  139.      * @param provider the string name of the provider.
  140.      *
  141.      * @return the new KeyPairGenerator object.
  142.      *
  143.      * @exception NoSuchAlgorithmException if the algorithm is
  144.      * not available from the provider.
  145.      *
  146.      * @exception NoSuchProviderException if the provider is not
  147.      * available in the environment. 
  148.      * 
  149.      * @see Provider 
  150.      */
  151.     public static KeyPairGenerator getInstance(String algorithm,
  152.                            String provider) 
  153.     throws NoSuchAlgorithmException, NoSuchProviderException {    
  154.     return (KeyPairGenerator)Security.getImpl(algorithm, 
  155.                           "KeyPairGenerator",
  156.                           provider);
  157.     }
  158.  
  159.     /**
  160.      * Initializes the key pair generator for a certain strength.
  161.      *
  162.      * @param strength the strength of the key. This is an
  163.      * algorithm-specific metric, such as modulus length.
  164.      *
  165.      * @param random the source of randomness for this generator.
  166.      */
  167.     public abstract void initialize(int strength, SecureRandom random);
  168.  
  169.     /**
  170.      * Initializes the key pair generator for a certain strength using
  171.      * a system-provided source of randomness.
  172.      *
  173.      * @param strength the strength of the key. This is an
  174.      * algorithm-specific metric, such as modulus length.
  175.      */
  176.     public void initialize(int strength) {
  177.     initialize(strength, new SecureRandom());
  178.     }
  179.  
  180.  
  181.     /**
  182.      * Generates a key pair. Unless an initialization method is called
  183.      * using a KeyPairGenerator interface, algorithm-specific defaults
  184.      * will be used. This will generate a new key pair every time it
  185.      * is called.
  186.      */
  187.     public abstract KeyPair generateKeyPair();
  188. }
  189.